1   /*
2    * Copyright (C) 2008 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package com.google.common.collect.testing.features;
18  
19  import com.google.common.annotations.GwtCompatible;
20  import com.google.common.collect.testing.Helpers;
21  
22  import java.lang.annotation.Inherited;
23  import java.lang.annotation.Retention;
24  import java.lang.annotation.RetentionPolicy;
25  import java.util.Collection;
26  import java.util.LinkedHashSet;
27  import java.util.Set;
28  import java.util.SortedSet;
29  
30  /**
31   * Optional features of classes derived from {@code Collection}.
32   *
33   * @author George van den Driessche
34   */
35  // Enum values use constructors with generic varargs.
36  @SuppressWarnings("unchecked")
37  @GwtCompatible
38  public enum CollectionFeature implements Feature<Collection> {
39    /**
40     * The collection must not throw {@code NullPointerException} on calls
41     * such as {@code contains(null)} or {@code remove(null)}, but instead
42     * must return a simple {@code false}.
43     */
44    ALLOWS_NULL_QUERIES,
45  
46    ALLOWS_NULL_VALUES (ALLOWS_NULL_QUERIES),
47  
48    /**
49     * Indicates that a collection disallows certain elements (other than
50     * {@code null}, whose validity as an element is indicated by the presence
51     * or absence of {@link #ALLOWS_NULL_VALUES}).
52     * From the documentation for {@link Collection}:
53     * <blockquote>"Some collection implementations have restrictions on the
54     * elements that they may contain.  For example, some implementations
55     * prohibit null elements, and some have restrictions on the types of their
56     * elements."</blockquote>
57     */
58    RESTRICTS_ELEMENTS,
59  
60    /**
61     * Indicates that a collection has a well-defined ordering of its elements.
62     * The ordering may depend on the element values, such as a {@link SortedSet},
63     * or on the insertion ordering, such as a {@link LinkedHashSet}. All list
64     * tests and sorted-collection tests automatically specify this feature.
65     */
66    KNOWN_ORDER,
67  
68    /**
69     * Indicates that a collection has a different {@link Object#toString}
70     * representation than most collections. If not specified, the collection
71     * tests will examine the value returned by {@link Object#toString}.
72     */
73    NON_STANDARD_TOSTRING,
74  
75    /**
76     * Indicates that the constructor or factory method of a collection, usually
77     * an immutable set, throws an {@link IllegalArgumentException} when presented
78     * with duplicate elements instead of collapsing them to a single element or
79     * including duplicate instances in the collection.
80     */
81    REJECTS_DUPLICATES_AT_CREATION,
82  
83    SUPPORTS_ADD,
84    SUPPORTS_REMOVE,
85    SUPPORTS_ITERATOR_REMOVE,
86    FAILS_FAST_ON_CONCURRENT_MODIFICATION,
87  
88    /**
89     * Features supported by general-purpose collections -
90     * everything but {@link #RESTRICTS_ELEMENTS}.
91     * @see java.util.Collection the definition of general-purpose collections.
92     */
93    GENERAL_PURPOSE(
94        SUPPORTS_ADD,
95        SUPPORTS_REMOVE,
96        SUPPORTS_ITERATOR_REMOVE),
97  
98    /** Features supported by collections where only removal is allowed. */
99    REMOVE_OPERATIONS(
100       SUPPORTS_REMOVE,
101       SUPPORTS_ITERATOR_REMOVE),
102 
103   SERIALIZABLE, SERIALIZABLE_INCLUDING_VIEWS(SERIALIZABLE),
104   
105   SUBSET_VIEW,
106   DESCENDING_VIEW,
107 
108   /**
109    * For documenting collections that support no optional features, such as
110    * {@link java.util.Collections#emptySet}
111    */
112   NONE;
113 
114   private final Set<Feature<? super Collection>> implied;
115 
116   CollectionFeature(Feature<? super Collection> ... implied) {
117     this.implied = Helpers.copyToSet(implied);
118   }
119 
120   @Override
121   public Set<Feature<? super Collection>> getImpliedFeatures() {
122     return implied;
123   }
124 
125   @Retention(RetentionPolicy.RUNTIME)
126   @Inherited
127   @TesterAnnotation
128   public @interface Require {
129     CollectionFeature[] value() default {};
130     CollectionFeature[] absent() default {};
131   }
132 }